docs(flux2): clarify image= is reference conditioning, not img2img by NazarKozak · Pull Request #13557 · huggingface/diffusers

NazarKozak · 2026-04-25T06:35:12Z

What does this PR do?

The image= parameter on Flux2Pipeline and Flux2KleinPipeline is currently described as a "starting point", which mirrors the SD/Flux.1 img2img wording:

Image, numpy array or tensor representing an image batch to be used as the starting point. […] It can also accept image latents as image, but if passing latents directly it is not encoded again.

Flux.2 actually encodes reference images as additional attention conditioning tokens — there's no noisy-latent init, and so no strength parameter. The existing wording is easy to misread when porting code from StableDiffusionImg2ImgPipeline, FluxImg2ImgPipeline, or FluxKontextInpaintPipeline, all of which legitimately accept strength.

We had a production serving stack pass strength= alongside image= based on the existing wording and crashed with:

TypeError: Flux2Pipeline.__call__() got an unexpected keyword argument 'strength'

Changes

Rewrite the image= docstring on Flux2Pipeline.__call__ and Flux2KleinPipeline.__call__ to make it explicit that this is reference conditioning, not img2img, and that there is no strength knob.
Add a short ## Reference conditioning vs. img2img callout to docs/source/en/api/pipelines/flux2.md distinguishing the two modes, mentioning Flux2KleinInpaintPipeline as the right pipeline if you actually do need a strength-style noisy-latent init.

Flux2KleinKVPipeline's docstring already correctly describes reference conditioning, so no change there. Flux2KleinInpaintPipeline does take strength and is left as-is.

Out of scope (happy to add as a follow-up)

A small defensive check inside __call__ that intercepts unknown img2img kwargs and raises a clear TypeError pointing at this section of the docs, e.g.:

if "strength" in kwargs:
    raise TypeError(
        "Flux2Pipeline does not support `strength`. Flux.2 uses reference "
        "conditioning via `image=`, not noisy-latent img2img. See "
        "https://huggingface.co/docs/diffusers/api/pipelines/flux2 ."
    )

Left out of this PR to keep it docs-only; happy to push as a second commit if maintainers prefer.

Behavioral change

None — docs only.

Fixes # (no related issue — surfaced in production)

Before submitting

This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
Did you read the contributor guideline?
Did you read our philosophy doc (important for complex PRs)?
Was this discussed/approved via a GitHub issue or the forum? Please add a link to it if that's the case.
Did you make sure to update the documentation with your changes?
Did you write any new necessary tests? (N/A — docs only)

Who can review?

Docs: @stevhliu @sayakpaul

stevhliu

docs lgtm, handing off to @sayakpaul for final look :)

stevhliu · 2026-04-27T15:58:43Z

+The `image` argument on `Flux2Pipeline` and `Flux2KleinPipeline` is **reference conditioning**, not
+img2img. Reference images are encoded into additional attention tokens that flow through the
+transformer alongside the text prompt — there is no noisy latent initialization, and so no `strength`
+parameter to scale.


Suggested change

The `image` argument on `Flux2Pipeline` and `Flux2KleinPipeline` is **reference conditioning**, not

img2img. Reference images are encoded into additional attention tokens that flow through the

transformer alongside the text prompt — there is no noisy latent initialization, and so no `strength`

parameter to scale.

The `image` argument on [`Flux2Pipeline`[ and [`Flux2KleinPipeline`] is a *reference conditioning*. Reference images are encoded as additional attention tokens that flow through the

transformer alongside the text prompt. Flux.2 doesn't add noise to the input image unlike [`FluxImg2ImgPipeline`]. Passing `strength` to [`Flux2Pipeline`] raises:

stevhliu · 2026-04-27T16:00:28Z

+This differs from `StableDiffusionImg2ImgPipeline`, `FluxImg2ImgPipeline`, and
+`FluxKontextInpaintPipeline`, which add noise to a latent encoding of the input image and then
+partially denoise it. If you port code from those pipelines and pass `strength=...` to a Flux.2
+pipeline, you will see:


Suggested change

This differs from `StableDiffusionImg2ImgPipeline`, `FluxImg2ImgPipeline`, and

`FluxKontextInpaintPipeline`, which add noise to a latent encoding of the input image and then

partially denoise it. If you port code from those pipelines and pass `strength=...` to a Flux.2

pipeline, you will see:

stevhliu · 2026-04-27T16:01:31Z

+Drop the `strength` kwarg and pass references via `image=` (a single image, or a list for multiple
+references). For Flux.2 inpainting (which does add noise to a latent and therefore does take a
+`strength` parameter), use `Flux2KleinInpaintPipeline` instead.


Suggested change

Drop the `strength` kwarg and pass references via `image=` (a single image, or a list for multiple

references). For Flux.2 inpainting (which does add noise to a latent and therefore does take a

`strength` parameter), use `Flux2KleinInpaintPipeline` instead.

Drop the `strength` argument and pass references with `image`. For inpainting, use [`Flux2KleinInpaintPipeline`] instead.

@stevhliu

Apply @stevhliu's suggestions: - Compress 'Reference conditioning vs. img2img' section. - Use [`ClassName`] cross-reference syntax for Flux2Pipeline, Flux2KleinPipeline, FluxImg2ImgPipeline, Flux2KleinInpaintPipeline. - Drop the 'This differs from...' paragraph; the TypeError example alone makes the point.

NazarKozak · 2026-04-27T21:18:53Z

Thanks for the review @stevhliu! Applied all three suggestions in 2db8a9e — tightened the wording and switched to [ClassName] cross-reference syntax. (Fixed a small bracket typo in the first suggestion: [Flux2Pipeline] instead of [Flux2Pipeline[.)

@sayakpaul — ready for your final look whenever you have a moment 🙏

docs(flux2): clarify image= is reference conditioning, not img2img

d67491e

github-actions Bot added documentation Improvements or additions to documentation pipelines size/S PR with diff < 50 LOC labels Apr 25, 2026

stevhliu approved these changes Apr 27, 2026

View reviewed changes

github-actions Bot added size/S PR with diff < 50 LOC and removed size/S PR with diff < 50 LOC labels Apr 27, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(flux2): clarify image= is reference conditioning, not img2img#13557

docs(flux2): clarify image= is reference conditioning, not img2img#13557
NazarKozak wants to merge 2 commits intohuggingface:mainfrom
NazarKozak:docs/flux2-image-arg-clarification

NazarKozak commented Apr 25, 2026 •

edited

Loading

Uh oh!

stevhliu left a comment

Uh oh!

stevhliu Apr 27, 2026

Uh oh!

stevhliu Apr 27, 2026

Uh oh!

stevhliu Apr 27, 2026

Uh oh!

NazarKozak commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

NazarKozak commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Changes

Out of scope (happy to add as a follow-up)

Behavioral change

Before submitting

Who can review?

Uh oh!

stevhliu left a comment

Choose a reason for hiding this comment

Uh oh!

stevhliu Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

stevhliu Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

stevhliu Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

NazarKozak commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

NazarKozak commented Apr 25, 2026 •

edited

Loading